﻿<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
	<head>
		<title></title>
		<link rel="Stylesheet" href="Resources/Style.css" />
	</head>
	<body>
	    <div class="header">TFS WORKITEM WATCHER</div> 

        <div class="main">
            <h2>Index</h2>
            
            <ul class="index">
                <li>
                    <a href="#About"><b>About</b></a>
                </li>
                <li>
                    <a href="#Requirements"><b>Requirements</b></a>
                </li>
                <li>
                    <a href="#DefaultInstall"><b>Installation with default settings</b></a>
                </li>
                <li>
                    <a href="#TroubleShooting"><b>Trouble shooting</b></a>
                </li>
                <li>
                    <a href="#Architecture"><b>Architectural concepts</b></a>
                </li>
                <li>
                    <a href="#CredentialsProviders"><b>Provided CredentialsProviders</b></a>
                </li>
                <li>
                    <a href="#ObserverAccountProviders"><b>Provided ObserverAccountProviders</b></a>
                </li>
                <li>
                    <a href="#NotifyProviders"><b>Provided NotifyProviders</b></a>
                </li>
                <li>
                    <a href="#OwnCredentialsProvider"><b>Implementing an own CredentialsProvider</b></a>
                </li>
                <li>
                    <a href="#OwnObserverAccountProvider"><b>Implementing an own ObserverAccountProvider</b></a>
                </li>
                <li>
                    <a href="#OwnNotifyProvider"><b>Implementing an own NotifyProvider</b></a>
                </li>
            </ul>
            
            <p class="separation" />
            
            <h2><a name="About">About</a></h2>
            
            <p>
                TFSWIWatcher is a service which allows you to register for watching workitems in Team Foundation Server. The service can be configured to use different logic to retrieve accounts to be notified and to deliver messages to the accounts to be notified.
            </p>
            
            <p>
                By default TFSWIWatcher watches all changes of workitems and determines the 
                accounts to be notified by looking up the texbox in a new tab of the workitem 
                called Observers. This tab holds a list of account names - each account name on a 
                singe line:
            </p>

            <img src="Resources/ObserverTab.jpg" alt="Observer Tab" />
            
            <p>
                <span lang="EN-US">TFSWIWatcher will then determine the email addresses of the 
                provided account names and will send a mail to each account.</span>
            </p>
            
            <p class="separation" />
            
            <h2><a name="Requirements">Requirements</a></h2>
            
            <ul class="index">
                <li>
                    <a href="http://www.microsoft.com/downloads/details.aspx?familyid=ab99342f-5d1a-413d-8319-81da479ab0d7&displaylang=en"><b>Microsoft .NET Framework 3.5 Service Pack 1</b></a>
                </li>
                <li>
                    <a href="http://msdn.microsoft.com/en-us/tfs2008/bb980963.aspx"><b>Visual Studio 
					Team System 2010 Team Foundation Server Power Tools</b></a>
                </li>
            </ul>
            
            <p class="separation" />
            
            <h2><a name="DefaultInstall">Installation with default settings</a></h2>
            
            <div class="lightIndent">
                <h3>.Net Framework 3.5 SP 1 Installation</h3>
                <p>
                    If you've not already installed .Net Framework 3.5 please download and install it using the link under <b>>> <a href="#Requirements">Requirements</a> <<</b>.
                </p>
                
                <h3>Team Foundation Power Tools Installation</h3>
                <p>
                    If you've not already installed TFPT please download and install it using the link under <b>>> <a href="#Requirements">Requirements</a> <<</b>. You will need TFPT to complete the next step.
                </p>
                
                <h3>Adding the Observer-Tab for Workitems</h3>
                <p>
                    After installing TFPT there will be a new Menu under Tools called "Process Editor":
                </p>
                
                <img src="Resources/OpenWITMenu.jpg" alt="Open Workitem Menu" />
                
                <p>
                    Please navigate to the selection in the above screenshot.
                </p>
                <p>
                    In the next dialog choose one of the provided workitem types (you will need to reapeat the following steps for all other types):
                </p>
                
                <img src="Resources/SelectWorkItemType.jpg" alt="Select Work Item Type" />
                
                <p>
                    In the next dialog click "New" and fill the poup with the Information from the screenshot and press "ok":
                </p>
                
                <img src="Resources/FieldDefinition.jpg" alt="Field Definition" />
                
                <p>
                    In the next dialog click "New" and fill the poup with the Information from the screenshot and press "ok":
                </p>
                
                <img src="Resources/WorkitemLayout.jpg" alt="Work Item Layout" />
                
                <p>
                    Call it "Observers":
                </p>
                
                <img src="Resources/ObserverTabLabel.jpg" alt="Tab Page Name" />
                
                <p>
                    Add a "New Control" to the newly created Tab Page:
                </p>
                
                <img src="Resources/NewControlOnTab.jpg" alt="New control on tab" />
                
                <p>
                    Configure the Control exactly as in the following screenshot:
                </p>
                
                <a name="FieldName">
                    <img src="Resources/NewControlOnTabOptions.jpg" alt="New control on tab options" />
                </a>
                
                <p>
                    Save the result and after opening a workitem you'll have a new Tab "Observers":
                </p>
                
                <h3>Settings in TFSWIWatcher.Service.exe.config</h3>
                <p>
                    There are 2 important sections <strong>ConfigSettings</strong> and <strong>system.net</strong>.  Please change the <strong>Teamserver</strong> in <strong>ConfigSettings</strong> and if the provided port conflicts with another app on the server running TFSWIWatcher please also change the <strong>port</strong>:
                </p>
                
                <img src="Resources/BasicConfigSettings.jpg" alt="Basic Config Settings" />
                
                <p>
                    After this please configure your mail settings in the following section:
                </p>
                
                <img src="Resources/MailSettings.jpg" alt="Mail Settings" />
                
                <h3>Installing the service</h3>
                <p>
                    Just run the <strong>install.bat</strong> script to install the service. You will be prompted for credentials the service should run with. Please specify an account having enough rights for the Team Foundation Server.
                </p>
                
                <h3>Start-Options for the Service</h3>
                <p>
                    After installing the service, the service can be found in the service control panel as <strong>TFSWIWatcherService</strong>. Configure the service like in the following screenshot:
                </p>
                
                <img src="Resources/ServiceSettings.jpg" alt="Service Settings" />
            </div>
            
            <p class="separation" />
            <h2><a name="TroubleShooting">Trouble shooting</a></h2>
            
            <p>
                When errors arise they are logged to a file named
                <strong>log.txt</strong>. Lo4Net is used for logging. You can change the way logging is done through modifying the following 
                section:</p>
            
            <img src="Resources/Log4NetConfig.jpg" alt="Log4Net" />
            
            <p>
                More
                information about how to change this config and which possibilities exist can be found 
                at the <b>&gt;&gt; <a href="http://logging.apache.org/log4net/">Log4Net website</a> &lt;&lt;</b>.</p>
            
            <p class="separation" />
            <h2><a name="Architecture">Architectural concepts</a></h2>
            
            <div class="lightIndent">
                <h3>Overview</h3>
                <br />
                <a href="Resources/ArchitectureOverview.jpg">
                    <img src="Resources/ArchitectureOverviewSmall.jpg" border="1" alt="Architecture Overview" />
                </a>
                <br />
                    
                <h3>1. Getting notified about workitem changes</h3>
                <p>
                    On startup the windows service is creating a windows communication foundation 
                    host. It then registeres the wcf host endpoint with team foundation server using 
                    the tfs api. The type of registration is soap. On successful registration with 
                    tfs the service is getting a unique id for the registration. When the service is 
                    shutting down, the unique id is used to unsubscribe from getting further events. 
                    To connect to tfs the service is using a CredentialsProvider which is configured 
                    in the configuration file TFSWIWatcher.Service.exe.config under the 
                    configuration node <strong>CredentialsProvider</strong>. By default the service is using 
                    the <strong>UICredentialsProvider</strong> which takes the credentials the service runs with to 
                    connect to tfs. More information about CredentialsProviders are under <b>&gt;&gt; <a href="#CredentialsProviders">this section</a> 
                    &lt;&lt;</b>.</p>
                    
                
                <h3>2. Determining accounts to notify</h3>
                <p>
                    
                    In the configuration file TFSWIWatcher.Service.exe.config there is a section 
                    called <strong>ObserverAccountProviders</strong>. This section lists all providers 
                    collecting accounts to notify. By default there is a single provider in this 
                    list called <strong>TFSObserverAccountProvider</strong>. This provider gets the accounts 
                    from the observer field in the workitem that was changed by parsing the field 
                    line (account name) by line (account name). More information about 
                    ObserverAccountProviders are under <b>&gt;&gt; <a href="#ObserverAccountProviders">this section</a> 
                    &lt;&lt;</b>.</p>
                    
                <h3>3. Notifying accounts</h3>
                <p>
                    
                    In the configuration file TFSWIWatcher.Service.exe.config there is a section 
                    called <strong>NotifyProviders</strong> . This section lists all providers 
                    notifying accounts. By default there is a single provider in this 
                    list called <strong>MailNotifyProvider</strong>. This provider notifies the 
                    accounts by getting there mail addresses from user profile and sending them a 
                    mail containing a change report. More information about 
                    NotifyProviders are under <b>&gt;&gt; <a href="#CredentialsProviders">this section</a> 
                    &lt;&lt;</b>.</p>
            </div>
            
            <p class="separation" />
            <h2><a name="CredentialsProviders">Provided CredentialsProviders</a></h2>
            
            <div class="lightIndent">
                <h3>Choosing a CredentialsProvider</h3>
                <p>
                    You can change the CredentialsProvider by changing the values of <strong>assemblyName</strong> and <strong>providerClass</strong> in config <strong>TFSWIWatcher.Service.exe.config</strong>:
                </p>
                <img src="Resources/CredentialsProviderConfigSection.jpg"alt="Credentials Provider Config Section" />
                <p>
                
                    The above configuration is for the CredentialsProvider <strong>UICredentialsProvider</strong>, 
                    which is the default provider.</p>
                
            
                <h3>1. UICredentialsProvider</h3>
                <p>
                    
                    This provider is the default CredentialsProvider to use it just change the <strong>CredentialsProvider section</strong> to 
                    look like the one under heading <strong>Choosing a CredentialsProvider</strong>.This 
                    provider takes the credentials the service is running with and communictaes with 
                    team foundation server using this credentials. To use this provider the service 
                    should be cofigured to run with an account having enough rights to communicate 
                    with team foundation server. This provider has no further configuration 
                    settings.</p>
                    
                <h3>2. ConfigCredentialsProvider</h3>
                <p>
                    
                    This provider uses predefined credentials which are configured in config <strong>TFSWIWatcher.Service.exe.config</strong> to communicate with team foundation server. 
                    This his helpful if you want to run the service with very few permissions. Or if 
                    the service is running at a different server then team foundation server and 
                    your running team foundation server without a domain. In this case you&#39;re not 
                    able to run the service under an account name which is able to communicate with 
                    team foundation server. To choose this provider change the <strong>CredentialsProvider section </strong> 
                    to look like the following section:</p>
                    
                <img src="Resources/ConfigCredentialsProviderChoice.jpg" alt="Config Credentials Provider Choice" />
                
                <p>
                    
                    The next step is to register a configuration section for this provider. This 
                    configuration section is used to provider the username, password and domain:</p>
                    
                <img src="Resources/ConfigCredentialsProviderConfigSectionSetup.jpg" alt="Config Credentials Provider Config Section Setup" />
                
                <p>
                    The last step is to add the section where you need to provide the credentials used to connect to team foundation server. 
                    In the following case you see the credentials I&#39;ve used to connect to during 
                    development to test on the VPC image microsoft has provided to test team 
                    foundation server:</p>
                    
                <img src="Resources/CredentialsProviderConfigSectionSample.jpg" alt="Credentials Provider Config Section Sample" />
            </div>
            
            <p class="separation" />
            <h2><a name="ObserverAccountProviders">Provided ObserverAccountProviders</a></h2>
            
            <div class="lightIndent">
                <h3>Choosing an ObserverAccountProvider</h3>
                <p>
                    You can add/remove/enable/disable an ObserverAccountProvider by changing the <strong>ObserverAccountProviders section</strong>. By default this section looks like the section below:
                </p>
                
                <img src="Resources/ObserverAccountProvidersSection.jpg" alt="Observer Account Providers Section" />
                
                <p>
                    The above configuration is for the <strong>TFSObserverAccountProvider</strong>, which is the default 
                    ObserverAccountProvider. Compared to CredentialsProviders there can be multiple 
                    ObserverAccountProviders. You can disabled a provider by setting the <strong>enabled</strong> attribute to false or by removing the provider from the ObserverAccountProviders section.</p>
                    
                <h3>1. TFSObserverAccountProvider</h3>
                <p>
                    This provider is the default ObserverAccountProvider
                    to use it just add the line from the above heading. This provider needs further 
                    information which is configured using a custom configuration section. This 
                    section must be registered using the following line:</p>
                    
                <img src="Resources/TFSObserverAccountProviderConfigSectionregistration.jpg" alt="TFSObserverAccountProvider ConfigSection Registration" />
                
                <p>
                    The last step is to add the following section and to customize the settings:
                </p>
                
                <img src="Resources/TFSObserverAccountProviderConfigSection.jpg" alt="TFSObserverAccountProvider ConfigSection" />
                
                <p>
                    The setting <strong>ObserverFieldName</strong> is the field of the workitem where the TFSObserverAccountProvider searches for accounts to notify.
                    The default field name is <strong>DNE.Observers</strong>. You can change the name of the field but dont forgett to consider it in <b>
                    &gt;&gt; <a href="#FieldName">this step</a> &lt;&lt;</b>.The <strong>RegexPattern</strong> and 
                    <strong>RegexOptions</strong> field is used to extract the account names from the field holding 
                    the account names. The regular expression used here extracts the account names 
                    line by line. If you want to change the regular expression please consider 
                    having a group called <strong>user</strong> in your regular expression - this is mandatory. 
                    The provider also checks the observers of the previous workitem revision and 
                    will send a single notify mail to accounts that where removed from the list of 
                    observers, so that those observers can detect an unwanted removal from the 
                    list of observer. The Projects-Node is commented out and allows you to define 
					which projects are observed and which types of workitems are observed in that 
					project. By default all projects and all workitem types are observed.</p>
                    
                <h3>1. XMLObserverAccountProvider</h3>
                <p>
                
                    This ObserverAccountProvider is used to define which account gets notified when 
                    a workitem changed using a xml config file. Here is a saple config file:</p>
                    
                <img src="Resources/XMLObserverAccountProviderFileSample.jpg" alt="XMLObserverAccountProvider File Sample" />
                
                <p>
                    In the above example "TFS Setup" will be notified about all changes of every workitem (*). "Darren" will be notified about changes to workitems with ID: 15,11,13,2,3,4,5,6 or 1. And "Brian" will be notified about changes to workitems with ID: 15,2,3,4,5,6 or 7.
                    As you can see in the example its possible to get <strong>notified about changes of all 
                    workitems</strong> using a star (*). Its possible to provide <strong>single IDs</strong> as well as <strong>ranges 
                    of IDs</strong> using a a hyphen between two IDs. To enable this provider add the following line to your 
                    <strong>ObserverAccountProviders section</strong>:</p>
                
                <img src="Resources/XMLObserverAccountProviderRegistration.jpg" alt="XMLObserverAccountProvider Registration" />
                
                <p>
                    This provider needs further information which is configured using a custom 
                    configuration section. This section must be registered using the following line:</p>
                    
                <img src="Resources/XMLObserverAccountProviderConfigRegistration.jpg" alt="XMLObserverAccountProvider Config Registration" />
                
                <p>
                    The last step is to add the following section and to customize the settings:
                </p>
                
                <img src="Resources/XMLObserverAccountProviderConfig.jpg" alt="XMLObserverAccountProvider Config" />
                
                <p>
                    The only setting here is the <strong>file</strong> where to find the xml defining which account gets 
                    notified for which workitem change.</p>
            </div>
            
            <p class="separation" />
            
            <h2><a name="NotifyProviders">Provided NotifyProviders</a></h2>
            
            <div class="lightIndent">
                <h3>Choosing a NotifyProvider</h3>
                <p>
                    You can add/remove/enable/disable a NotifyProvider by changing the <strong>NotifyProviders section</strong>. By default this section looks like the section below:
                </p>
                
                <img src="Resources/NotifyProviders.jpg" alt="Notify Providers" />
                
                <p>
                    The above configuration is for the <strong>MailNotifyProvider</strong>, which is the default 
                    NotifyProvider. Compared to CredentialsProviders there can be multiple 
                    NotifyProviders. You can disabled a provider by setting the <strong>enabled</strong> attribute to false or by removing the provider from the NotifyProviders section.</p>
                
                <h3>1. MailNotifyProvider</h3>
                <p>
                    This provider is notifying accounts through sending mails. The mail address of the account names is determined through team foundation server API. 
                    This provider is the default NotifyProvider, to use it just add the line from 
                    the above heading. This provider needs further information which is configured 
                    using a custom configuration section. This section must be registered using the 
                    following line:</p>
                
                <img src="Resources/MailNotifyConfigRegistration.jpg" alt="Mail Notify Config Registration" />
                
                <p>
                    The next step is to add the following section and to customize the settings:
                </p>
                
                <img src="Resources/MailNotifyConfig.jpg" alt="Mail Notify Config" />
                
                <p>
                    The only thing you can do in the above section is to provide the path to a 
                    filename acting as a xsl transformation or you can modify the existing file to 
                    satisfy your needs. 
                    The last step is to configure the settings for sending the mails: 
                </p>
                
                <img src="Resources/MailSettings.jpg" alt="Mail Settings" />
            </div>
            
            <p class="separation" />
            
            <h2><a name="OwnCredentialsProvider">Implementing an own CredentialsProvider</a></h2>
            
            <div class="lightIndent">
                <p>
                    To implement your own CredentialsProvider just create a project and reference the assembly <strong>Microsoft.TeamFoundation.Client</strong> and create a class implementing the interface <strong>ICredentialsProvider</strong> which is located in namespace <strong>Microsoft.TeamFoundation.Client</strong>. The interface has the following definition: 
                </p>
                
                <img src="Resources/ICredentialsProvider.jpg" alt="ICredentialsProvider" />
            </div>
            
            <p class="separation" />
            
            <h2><a name="OwnObserverAccountProvider">Implementing an own ObserverAccountProvider</a></h2>
            
            <div class="lightIndent">
                <p>
                    To implement your own ObserverAccountProvider just create a project and reference the assembly <strong>TFSWIWatcher.BL</strong> and create a class implementing the interface <strong>IObserverAccountProvider</strong> which is located in namespace <strong>TFSWIWatcher.BL.Providers</strong>. The interface has the following definition: 
                </p>
                
                <img src="Resources/IObserverAccountProvider.jpg" alt="IObserverAccountProvider" />
                
                <p>
                    The method <strong>Initialize()</strong> is called once by the service to allow the implementing provider to read configuration settings and to do other initialization stuff. The method <strong>GetObservers(..)</strong> is called each time a workitem change has occured. The implementing provider should return a list of accounts to be notified for this workitem change. The <strong>context parameter</strong> provides the implementing provider with information about the workitem and so on.
                </p>
            </div>
            
            <p class="separation" />
            
            <h2><a name="OwnNotifyProvider">Implementing an own NotifyProvider</a></h2>
            
            <div class="lightIndent">
                <p>
                    To implement your own NotifyProvider just create a project and reference the assembly <strong>TFSWIWatcher.BL</strong> and create a class implementing the interface <strong>INotifyProvider</strong> which is located in namespace <strong>TFSWIWatcher.BL.Providers</strong>. The interface has the following definition: 
                </p>
                
                <img src="Resources/INotifyProvider.jpg" alt="INotifyProvider" />
                
                <p>
                    The method <strong>Initialize()</strong> is called once by the service to allow the implementing provider to read configuration settings and to do other initialization stuff. The method <strong>Notify(..)</strong> is called each time a workitem change has occured. The implementing provider gets passed a list of accounts to notify for this workitem change as well as a context parameter providing information about the workitem and so on.
                </p>
            </div>
        </div>
	</body>
</html>